docs/core/entity.md (2)

122-132: Fix grammar and consider adding a code example.

1. There's a grammatical error in the text. Please fix:

-If an attributes is not expected
+If an attribute is not expected

2. Consider adding a code example to illustrate these rules. For instance:

class MyEntity(Entity):
    @property
    def extra_state_attributes(self):
        """Return entity specific state attributes."""
        attributes = {
            "expected_attribute": self._value or None,  # Always present
            "configuration_dependent": "value"  # Only when configured
        }
        return attributes

🧰 Tools

🪛 LanguageTool

[grammar] ~131-~131: The plural noun “attributes” cannot be used with the article “an”. Did you mean “an attribute” or “attributes”?
Context: ...None` and remain in the dictionary - If an attributes is not expected, it should not be in th...

(A_NNS)

---

Line range hint 134-139: Consider enhancing the System properties documentation.

The section could be more helpful with additional context:

1. Add a note explaining that these properties are managed through the entity registry.
2. Add a warning about not implementing custom logic for these properties, as they are system-managed.

Example addition:

:::warning
These properties are managed by Home Assistant through the entity registry. Integrations should not implement custom logic for these properties as it may conflict with system behavior.
:::

🧰 Tools

🪛 LanguageTool

[grammar] ~131-~131: The plural noun “attributes” cannot be used with the article “an”. Did you mean “an attribute” or “attributes”?
Context: ...None` and remain in the dictionary - If an attributes is not expected, it should not be in th...

(A_NNS)

🪛 Markdownlint

120-120: Expected: 4; Actual: 3; Too few cells, row will be missing data
Table column count

(MD056, table-column-count)

Configuration used: CodeRabbit UI
Review profile: CHILL

docs/core/entity.md (2)

122-132: Enhance the state attributes section with examples

While the rules are clear, adding concrete examples would help developers better understand when attributes should be included or excluded from the dictionary. Consider adding examples for:

1. Expected attributes (e.g., supported features)
2. Attributes that should be None
3. Attributes that should not be in the dictionary

Here's a suggested addition after line 132:

- If an attribute is not expected, it should not be in the dictionary. An attribute is expected if supported by the entity, for example as indicated by `supported_features`.
+ If an attribute is not expected, it should not be in the dictionary. An attribute is expected if supported by the entity, for example as indicated by `supported_features`.
+
+ ### Examples
+
+ ```python
+ @property
+ def extra_state_attributes(self):
+     """Return entity specific state attributes."""
+     attributes = {}
+     
+     # Example 1: Expected attribute based on supported features
+     if self._attr_supported_features & SUPPORT_BRIGHTNESS:
+         attributes["brightness"] = self._brightness
+     
+     # Example 2: Expected attribute that might be None
+     if self._attr_supported_features & SUPPORT_COLOR:
+         attributes["rgb_color"] = self._rgb_color  # Could be None
+     
+     # Example 3: Conditional attribute that should not be included
+     # Don't do this:
+     # if self._is_dimmable:
+     #     attributes["brightness"] = self._brightness
+     
+     return attributes
+ ```

---

Line range hint 143-401: LGTM with a minor suggestion

The updated sections on entity naming and property implementation are clear and well-documented. The examples effectively demonstrate best practices. Consider adding a note about error handling in the property implementation example to make it more complete.

Add error handling to the example:

     def update(self) -> None:
         """Update entity state."""
         try:
             self._device.update()
-        except ExampleException:
+        except ExampleException as ex:
             if self.available:  # Read current state, no need to prefix with _attr_
-                LOGGER.warning("Update failed for %s", self.entity_id)
+                LOGGER.warning("Update failed for %s: %s", self.entity_id, str(ex))
             self._attr_available = False  # Set property value
             return
+        except Exception as ex:
+            LOGGER.error("Unexpected error updating %s: %s", self.entity_id, str(ex))
+            self._attr_available = False
+            return

🧰 Tools

🪛 Markdownlint

120-120: Expected: 4; Actual: 3; Too few cells, row will be missing data
Table column count

(MD056, table-column-count)

Configuration used: CodeRabbit UI
Review profile: CHILL

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

Cache: Disabled due to data retention organization setting

Knowledge base: Disabled due to data retention organization setting

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

Cache: Disabled due to data retention organization setting

Knowledge base: Disabled due to data retention organization setting